/*
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is ST_EXT-S_UIMAST.
 *
 * The Initial Developer of the Original Code is
 * University of Rome, Tor Vergata
 * Portions created by the Initial Developer are Copyright (C) 2009
 * the Initial Developer. All Rights Reserved.
 */

package it.uniroma2.art.uimast.xpts;

import java.util.Iterator;

import org.apache.uima.cas.CAS;

import it.uniroma2.art.ontapi.ARTResource;
import it.uniroma2.art.uimast.impl.AnnotationProjection;

/**
 * Provides the support for an export mode. The {@link AnnotationProjection}
 * uses an instance of this class to perform mode-dependent operations,
 * such as assigining a value to the wired-properties.
 * @author <a href="mailto:manuel.fiorelli@gmail.com">Manuel Fiorelli</a>
 */
public interface ExportModeDriver {
	
	/**
	 * Gets the name of the supported export mode. It must be equal to the value 
	 * returned by the method {@code ExportModeService#getModeName()} of the
	 * service, which creates this driver.
	 * @return
	 */
	String getModeName();
	
	/**
	 * A type representing the result of a check.
	 * @author <a href="mailto:manuel.fiorelli@gmail.com">Manuel Fiorelli</a>
	 */
	enum CheckResult { OK, UNSUPPORTED_WIRED_PROPERTY, INCOMPATIBLE_RANGE };
	
	/**
	 * Checks that a given wired property is supported. 
	 * @param uri a property
	 * @param v the variant which will used as prototype
	 * @throws Exception if an invalid URI or variant is provided
	 */
	CheckResult checkWiredProperty(ARTResource property, Variant v) throws Exception;
	
	/**
	 * Enters into a web page.
	 * @param webPage an instance of {@code ann:webpage}
	 * @param cas a reference to the current CAS
	 */
	void enterWebPage(ARTResource webPage, CAS cas) throws Exception;
	
	/**
	 * Enters into an annotation.
	 * @param domainObject an instance of {@code owl:Thing}
	 * @param annot an instance of {@code ann:RangeAnnotation}
	 */
	void enterAnnotation(ARTResource domainObject, ARTResource annot) throws Exception;

	/**
	 * Gets the values of of a given wired property.
	 * @param property a resource identifiyng the wired property
	 * @param v the variant which will be used as prototype
	 * @return an iterator over the sequence of property values
	 */
	Iterator<Variant> getWiredProperty(ARTResource property, Variant v);
}
